生成API文档

【关于API Blueprint】

dingo api允许我们使用命令：

php artisan api:doc --output-file "D:\api.apib"

生成API Blueprint 1A 格式的文档；前提是我们已经为我们的控制器和方法写好了注释，比如：

<?php
namespace App\Http\Controllers\Api\V1;

use Illuminate\Http\Request;
use App\Http\Requests;
use App\Http\Controllers\Controller;

/**
 * 用户资源    
 * 
 * <br/>[注意]：每个部门下的节点不能超过3万个。
 * 
 * @Resource("Group User")
 */
class UserController extends ApiBaseController
{
    /**
     * 根据用户ID获取用户
     * 
     * [需授权] 返回单个用户
     * 
     * @Get("/api/user/ID")
     * @Parameters({
     *      @Parameter("id", type="integer", required=true, description="用户ID")
     * })
     * @Request(headers={"Authorization": "Bearer token"})
     * @Response(200, body={})
     */
    public function show($id)
    {
       //
    }
    
}

像上面这样写好注释后，使用 api:doc 命令行就会生成标准的 api blueprint 文档了。

【关于aglio】

那么，我们现在有了markdown写法的api blueprint文档了，怎么把它转换成可读的html文档呢？aglio神器就来了。aglio的github地址：https://github.com/danielgtaylor/aglio 注意安装aglio需要先安装NODE.JS，然后利用NPM安装即可：

npm install -g aglio

至于怎么安装node.JS 不是本文的关注点，各位自行搜索。

好了，安装aglio完毕我们就可以使用命令行生成可读的html格式的api文档了：

aglio -i "D:\api.apib" -o "D:\api.html"

生成的api文档如下：

到此，一套比较完善的api文档就新鲜出炉啦。

为了避免每次都要打2次命令，我们可以写一个命令脚本 ApiCreate.bat，比如：

@echo off
echo "API Create Command Tool"
echo Current directory is: %cd%
cd %cd%
::先生成api blueprint格式文档
call php artisan api:doc --output-file %cd%"\api.apib"
::用aglio工具转化成html文档 --theme-full-width
call aglio -i %cd%"\api.apib" -o %cd%"\public\api.html"
pause

这样以后要生产api文档，只要点击执行该bat脚本就可以啦。

关于生成api文档还有另外一个不错的工具：Swagger http://swagger.io/ 飘易会在另外的文章里单独说一说。